Route Handlers replace API Routes with a more flexible, file-based system that supports streaming, Edge Runtime, CORS configuration, and direct access to Next.js caching, while running in both Node.js and Edge environments
Route Handlers are the App Router evolution of API Routes, offering a fundamentally different approach to building server-side endpoints. While API Routes were limited to the /pages/api directory and ran only in Node.js, Route Handlers leverage the file-system routing of the App Router—they can live anywhere in the app folder, not just under /api. More importantly, Route Handlers introduce capabilities that were impossible or complex with API Routes: streaming responses, Edge Runtime support, fine-grained cache control, and seamless integration with Next.js's caching layers.
Location flexibility: API Routes only exist in
/pages/api; Route Handlers can be defined anywhere in theappfolder usingroute.jsfiles, allowing co-location with related UI components.Runtime options: API Routes only support Node.js; Route Handlers support both Node.js and Edge runtimes, enabling ultra-fast responses from global edge locations.
Caching capabilities: API Routes had no built-in caching; Route Handlers integrate with Next.js's full caching system, supporting
revalidate,tags, andfetchcache options.Streaming support: Route Handlers can stream responses using web streams, enabling real-time data delivery and large file transfers; API Routes were limited to sending complete responses.
HTTP method handling: Both support standard methods (GET, POST, etc.), but Route Handlers provide a cleaner API with exported functions per method.
Middleware integration: Route Handlers automatically respect middleware and have access to the same runtime context, including cookies and headers.
Route Handlers can stream responses using web streams, enabling real-time data delivery, server-sent events, and efficient large file transfers. This was impossible with API Routes, which had to send the complete response at once. You can now build endpoints that progressively send data, improving perceived performance for large datasets or enabling live updates without WebSockets.
Route Handlers can run on the Edge Runtime, deploying your API endpoints to global edge locations for minimal latency. This is particularly valuable for personalization, geolocation-based responses, or any API that benefits from being close to users. You enable it with export const runtime = 'edge' in your route file. Edge Runtime has limitations (no Node.js APIs, smaller package size), but for many APIs, the performance benefits outweigh these constraints.
Route Handlers integrate with Next.js's caching layers, allowing you to use the same fetch cache options (next: { revalidate, tags }) that page components use. You can also set Cache-Control headers directly, and leverage revalidateTag and revalidatePath for on-demand invalidation. This creates a unified caching strategy across your entire application, from pages to API endpoints.
Co-location: Place route handlers next to the components that use them, improving code organization and maintainability.
Standard web APIs: Use Request and Response objects instead of Next.js-specific types, making code more portable and easier to test.
Middleware integration: Route Handlers automatically respect middleware and have access to the same context, including cookies and headers modified by middleware.
Dynamic segments: Route Handlers can use the same folder-based dynamic segments as pages (e.g.,
app/products/[id]/route.tsfor/api/products/123).Type safety: Better TypeScript inference with standard Request/Response types.
When migrating from API Routes to Route Handlers, the main changes are: moving from /pages/api to /app/api with route.ts files, replacing NextApiRequest/NextApiResponse with standard Request/NextResponse, and adopting the new pattern of exporting named functions for HTTP methods instead of a single default export. The official Next.js documentation provides a codemod (@next/codemod) to automate much of this migration.